\documentclass[a4paper,10pt]{article}
\usepackage{pylot}
\usepackage{pylotdevel}
\usepackage{wrapfig}

% ENCODAGE
% S'il y a des problèmes avec les accents ou pour passer en encodage
% (ISO-8859-15 == Europe de l'ouest) commentez les deux lignes suivantes :
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

% Langue du document, disponible : english, french
\selectlanguage{french}

% Meta-information du pdf, à compléter
\hypersetup{%
  pdfauthor=Guillaume Baty,%
  pdfcreator=LaTeX,%
  pdfkeywords=,%
  pdfsubject=,%
  pdftitle=,%
}

%-------------------------------------------------------------------------------
% Partie OPTIONNELLE
%-------------------------------------------------------------------------------
% % Placer le texte autour d'une figure
% \usepackage{wrapfig}

% % Pour les documentation contenant du code C++ ou Python, ajoute la coloration
% % syntaxique, la numérotation du code, ...
% % Paquet requis : lgrind
% \usepackage{pylotdevel}

\title{\pylottitle{Le titre}}
\author{Auteur}

\begin{document}
\DeclareGraphicsExtensions{.jpg,.png,.pdf} % permet d'insérer des images dans ces formats

\section{Installation de pyLot}

\subsection{Téléchargement et installation des programmes requis par pyLot}
\libname{pyLot} utilise des bibliothèques et programmes externes. Vous devez les installer avant de lancer l'interface d'installation de \libname{pyLot}.

\subsubsection{Programmes et bibliothèques logicielles \emph{obligatoires}}
\begin{itemize}
 \item[$\bullet$] CMake (2.6) \url{http://www.cmake.org/}
 \item[$\bullet$] Python (2.4) \url{http://www.python.org/}
 \item[$\bullet$] Qt (4.4) \url{http://www.qtsoftware.com/}
 \item[$\bullet$] PyQt (4.4) \url{http://www.riverbankcomputing.co.uk/software/}
 \item[$\bullet$] g++ \url{http://gcc.gnu.org/}
\end{itemize}

\n
Avant de commencer l'installation de pylot, vous \emph{devez absolument} installer tous ces programmes.

\n
\noindent Sous \emph{Linux}, tous ces programmes sont disponibles via les gestionnaire de paquets. En fonction de votre distribution, vous pouvez lancer une des commandes suivantes :
\begin{description}
 \item[Fedora :] yum install pyqt4 qt4 cmake gcc-c++
 \item[Mandriva :] urpmi install python-qt4 qt4 cmake gcc-c++
 \item[Ubuntu/Debian :] apt-get install python-qt4 qt4 cmake gcc-c++
 \end{description}

\n
\noindent Sous \emph{macOS}, installez les archives des sites officiels.

\n\noindent
\subsubsection{Programmes et bibliothèques logicielles \emph{optionnelles}}

\n
Pour la visualisation des résultats
\begin{itemize}
 \item[$\bullet$] Paraview \url{http://paraview.org/}
\end{itemize}

\n
Pour la génération automatique de documentation
\begin{itemize}
 \item[$\bullet$] doxygen \url{http://www.stack.nl/~dimitri/doxygen/}
 \item[$\bullet$] docutils \url{http://docutils.sourceforge.net/} (construire à partir des sources)
 \item[$\bullet$] epydoc \url{http://epydoc.sourceforge.net/}
 \item[$\bullet$] sphinx \url{http://sphinx.pocoo.org/}
\end{itemize}

\n
Pour le développement \libname{C++} et \libname{Python}
\begin{itemize}
 \item[$\bullet$] subversion (SVN) \url{http://subversion.tigris.org/}
 \item[$\bullet$] ipython \url{http://ipython.scipy.org/moin/}
\end{itemize}

\subsection{Installation de pyLot à partir d'une archive}
Commencez par décompresser l'archive (par exemple \fichier{pylot.tar.gz}) dans le dossier de votre choix (par exemple \fichier{/home/guillaume}).\\
Lancez un terminal, placez vous dans le dossier créé et lancez l'interface graphique à l'aide des commandes suivantes :
\begin{bash}
cd /home/guillaume/pylot
python pylot-install.py
\end{bash}

Une interface graphique apparaît. Si l'interface n'apparaît pas, veuillez consulter la partie \ref{part:buglancementinterface}.
\begin{center}
 \includegraphics[width=8cm]{./images/pylot-install-main.png}
 % pylot-install-main.png: 669x583 pixel, 72dpi, 23.60x20.57 cm, bb=
\end{center}

Sélectionnez les modules que vous souhaitez utiliser dans pyLot. Par exemple, pour la simulation de la cavité entraînée, sélectionnez \emph{Module Incompressible Flow}. Choisissez un répertoire d'installation (par exemple \fichier{/home/guillaume/Resources}).Tous les fichiers et dossiers seront installés dans ce répertoire. Choisissez donc de préférence un répertoire \emph{vide}.

\n
\warning{La case \emph{build dynamic librairies} est réservée aux utilisateurs experts et doit rester \emph{décochée}.}

\n
Après avoir choisi les modules et options, vous pouvez lancer la compilation et l'installation en appuyant sur le bouton \emph{Make Install}

\subsubsection{Utilisation avancée}
L'interface d'installation permet de compiler la bibliothèque avec des options de déboguage, de générer la documentation et d'exécuter des tests.

Le menu \guill{Build > Make} propose les actions suivantes :
\begin{description}
 \item[Make] compile la librairie
 \item[Make Install] compile la librairie et l'installe
 \item[Make Debug] compile la librairie pour une utilisation avec un débogueur
 \item[Make Doc] génère la documentation de pyLot et pylot
 \item[Make Test] compile et exécute les tests unitaires et les tests de régression
\end{description}

\subsection{Installation de pyLot à partir de SVN}

\warning{Ce type d'installation est réservée aux personnes souhaitant participer au développement de pyLot. Pour une simple utilisation, utilisez la méthode\guill{Installation de pyLot à partir d'une archive}}.

\warning{Vous devez être inscrit sur le site \url{http://gforge.inria.fr} et faire parti du projet pyLot.}

\subsubsection{Téléchargement de la version SVN}

Lancez un terminal et placez vous dans le dossier de votre choix. Récupérez ensuite la dernière version à l'aide de la commande SVN \guill{checkout}.
Par exemple, pour télécharger la dernière version dans votre dossier personnel :
\begin{bash}
cd ${HOME}
svn checkout svn+ssh://USER@scm.gforge.inria.fr/svn/pylot/Version2 pylot-src
\end{bash}
\emph{USER} est votre login gforge.

\n
Par la suite, pour mettre à jour votre version SVN, utilisez la commande \guill{update}.
\begin{bash}
cd ${HOME}/pylot-src
svn update
\end{bash}

Vous pouvez également utiliser le bouton \guill{SVN Update} de l'interface.

\subsection{Installation de pyLot en mode console (sans interface graphique)}

Vous pouvez installer pyLot sans interface graphique à l'aide de la commande

\begin{bash}
python pylot-install.py --install-pylot="dossier d'installation"
\end{bash}

Par exemple :
\begin{bash}
python pylot-install.py --install-pylot="/home/guillaume/Resources"
\end{bash}

Cette commande peut-être utile sur les machines ne disposant pas de serveurs
graphiques ou de version suffisamment récentes de PyQt ou Qt.

D'autres commandes sont disponibles. Pour les connaître, tapez simplement :

\begin{bash}
python pylot-install.py --help
\end{bash}

\section{Questions/Problèmes fréquents}

\subsubsection*{L'interface d'installation ne se lance pas}
\label{part:buglancementinterface}

\begin{question}
  Le message d'erreur se termine par \ibash{AttributeError: font\_grid}
\end{question}

\begin{reponse}
  Votre version de python-qt n'est pas assez récente, mettez python-qt à jour et recommencez (voir annexe \ref{appendix:majPyQt4}).
\end{reponse}

\begin{question}
  Le message d'erreur se termine par \vspace{-1em}
  \begin{verbatim}
	 "QVariant::load(QDataStream &s): type list unknown to QVariant"
  \end{verbatim}
\end{question}
\vspace{-2em}

\begin{reponse}
Supprimez les fichiers \fichier{\$\{HOME\}/.pylot/install/pylot-install.conf} et \fichier{\$\{HOME\}/.pylot/project/pylot-project.conf} puis relancez l'interface
\end{reponse}


\subsubsection*{L'interface d'installation se comporte anormalement}
\label{part:buginterface}
\begin{question}
  Les fichiers ne sont pas installés au bon endroit
\end{question}

\begin{reponse}
  Assurez vous qu'il n'existe pas de variable d'environnement \ibash{PYLOTRESOURCES}
\end{reponse}

\begin{question}
 Il n'y a pas d'options de compilation dans l'interface d'installation
\end{question}

\begin{reponse}
 Ceci est dû à un problème lors de l'exécution de \libname{cmake}. Le problème est sans doute :
 \begin{itemize}
  \item \libname{cmake} n'est pas installé ou la version est trop ancienne
  \item \libname{g++} n'est pas installé
 \end{itemize}
L'onglet processus donne des informations sur l'origine du problème. Une fois le problème résolu, supprimez (s'il existe) le fichier \fichier{../pylot-builds/CMakeCache.txt} et relancez l'interface.

\n
\includegraphics[height=5cm]{./images/no-options.png}\quad
\includegraphics[height=5cm]{./images/cmake-not-found-zoom.png}


\end{reponse}

\begin{question}
  Le programme semble s'exécuter mais je ne vois rien
\end{question}

\begin{reponse}
  La vue est simplement cachée, déplacez la avec la souris. Le problème ne ré-apparaîtra plus.
\begin{center}
 \includegraphics[width=8cm]{./images/bug-affichage-processus_solution.png}
 % bug-affichage-processus_solution.png: 754x320 pixel, 100dpi, 19.15x8.13 cm, bb=
\end{center}

\end{reponse}


\subsubsection*{Les chemins ne sont pas bons}
\begin{question}
  L'interface de projets ne va pas chercher les modèles ou les projets au bon endroit.
\end{question}

\begin{reponse}
 Quittez toutes les fenêtres ouvertes de pylot-project puis supprimez le fichier

 \fichier{\$\{HOME\}/.pylot/project/pathbook.csv}. Relancez l'interface.
\end{reponse}

\subsubsection*{L'interface d'installation se lance mais pas l'interface de simulation}
\begin{question}
  Le message d'erreur lors du lancement de l'interface de simulation se termine par :
  \begin{verbatim}
  from pylot.interfaces import UiInterface
ImportError: cannot import name UiInterface
  \end{verbatim}
\end{question}

\begin{reponse}
  Il y a un conflit avec une installation précédente. Supprimez les dossiers
 \fichier{python}, \fichier{etc}, \fichier{share} et \fichier{bin} qui
 se trouvent dans le dossier d'installation (\fichier{Resources} par exemple).
 Relancez l'installation.
\end{reponse}



\subsubsection*{Le problème n'apparaît pas dans la liste}
Si vous ne trouvez pas de solution à votre problème :
\begin{itemize}
 \item Vous avez un compte gforge : soumettez un bug dans l'onglet suivi de la gforge
 \item Vous n'avez pas de comptes gforge, envoyer un message à
 \begin{description}
  \item[Problème avec les interfaces graphiques] pierre.puiseux (a) univ-pau.fr
  \item[À compléter] ...
 \end{description}
\end{itemize}

\appendix

\section{Tester la version de développement de l'interface (\guill{branche})}

Cette annexe décrit la méthode pour tester la version de développement de
l'interface graphique (branche) avec le code pyLot \guill{\fichier{Version2}}.

\subsection*{Récupérer la version de développement}

\subsubsection*{Cas 1}
Si vous possedez tout l'arbre SVN, c'est-à-dire un dossier contenant les dossiers
\fichier{Version2}, \fichier{branches}, \fichier{ProgrammingHelp}, \dots

Allez dans le dossier de la branche \fichier{macros\_and\_scripts}
\begin{bash}
cd branches/macros_and_scripts
\end{bash}

puis créez des liens symboliques pointant vers tout les dossiers manquant de \fichier{Version2}:
\begin{bash}
ln -s ../../Version2/pyLot .
ln -s ../../Version2/pyLotAdaptiveMesh .
ln -s ../../Version2/pyLotMesh .
ln -s ../../Version2/pyLotMethods .
ln -s ../../Version2/pyLotModels .
ln -s ../../Version2/pyLotStructuredMesh .
ln -s ../../Version2/External .
\end{bash}

\subsubsection*{Cas 2}

vous n'avez que le dossier \fichier{Version2} sur votre disque.
mettez vous dans le dossier contenant \fichier{Version2}.
Téléchargez la branche

\begin{bash}
svn co svn+ssh://USER@scm.gforge.inria.fr/svn/pylot/branches/macros_and_scripts
\end{bash}

Allez dans le dossier de la branche \fichier{macros\_and\_scripts}
\begin{bash}
cd macros_and_scripts
\end{bash}

puis créez des liens symboliques pointant vers tout les dossiers manquant de \fichier{Version2} :
\begin{bash}
ln -s ../Version2/pyLot .
ln -s ../Version2/pyLotAdaptiveMesh .
ln -s ../Version2/pyLotMesh .
ln -s ../Version2/pyLotMethods .
ln -s ../Version2/pyLotModels .
ln -s ../Version2/pyLotStructuredMesh .
ln -s ../Version2/External .
\end{bash}

\subsection*{Installer la version de développement}
Cette version s'utilise de la même manière que les précédentes.
Vous devez juste passer l'option -\,-verbose pour faciliter le debogage.

\begin{bash}
python pylot-install.py --verbose
\end{bash}

Si l'interface n'apparaît pas, veuillez consulter la partie \ref{part:buglancementinterface}.

\warning{Vérifiez bien le chemin d'installation et changez le si nécessaire.}

Il est conseillé d'installer cette version dans votre dossier \guill{Resources}
habituel.

\subsection*{Utiliser l'interface de projets}

\warning{L'interface pour les projets s'appelle maintenant \fichier{pylot} et
non \fichier{pylot-project}}. Cette version s'utilise de la même manière que les précédentes :

\begin{bash}
.../Resources/bin/pylot --verbose
\end{bash}

\warning{Vérifiez le chemin des projets et changez le si nécessaire}

\subsection*{Continuer à developper le code}
Continuez à développer votre code dans \fichier{Version2} comme avant.
Vos changement seront directement pris en compte par la nouvelle interface.

\subsection*{Signaler un bug}
Si vous avez trouvé un bug, commencez par consulter la foire aux question de ce document
(Partie \ref{part:buginterface}) et la partie \guill{suivi, bug} de la gforge.
Si votre bug n'apparaît pas, ajoutez le sur la gforge.

\section{Mettre à jour PyQt}
\label{appendix:majPyQt4}

\subsection*{Linux}
\subsubsection*{Sous ubuntu 8.04 LTS}

Actuellement l'unique solution est de mettre à jour PyQt4 à
partir des sources. Voir "installer à partir
des sources".

\subsubsection*{Autres distributions linux}

Mettez à jour python-qt4 à l'aide du gestionnaire de paquets
(yum, yast, rpmdrake, synaptic, ...). Si aucune mise à jour
n'est proposée, essayez d'activer les dépots contenant des
versions plus récentes des paquets. Ces dépots sont généralement
nommés "backport", "testing",
"unstable", "pré-version" voir
"contrib".
Une fois python-qt4 mis à jour, vous pouvez désactiver le dépot.
Si aucune mise à jour n'est proposée, voir "installer
à partir des sources"

\subsection*{MacOS}
La méthode "Installer à partir des sources" devrait
fonctionner avec macOS. Pensez bien à changer "x11"
en "mac"

\subsection*{Installer à partir des sources}
L'installation à partir des sources se fait très facilement.
Toutes les étapes sont écrites dans le script bash suivant.

\begin{bash}
#!/bin/sh

SIPVERSION=4.9.1
PYQTVERSION=4.6.1

## You should remove old PyQt4 version ! To do that, uncomment next line
# sudo apt-get remove python-qt4 python-sip4

# Add qt4 headers
sudo apt-get install libqt4-dev

mkdir install-PyQt-${PYQTVERSION}
cd install-PyQt-${PYQTVERSION}

# Download and build python-sip (required for PyQt4 build)
wget http://www.riverbankcomputing.co.uk/static/Downloads/sip4/sip-${SIPVERSION}.tar.gz
tar xzvf sip-${SIPVERSION}.tar.gz
cd sip-${SIPVERSION}
python configure.py
make
sudo make install
cd ..

# Download and build PyQt4
wget http://www.riverbankcomputing.co.uk/static/Downloads/PyQt4/PyQt-x11-gpl-${PYQTVERSION}.tar.gz
tar xzvf PyQt-x11-gpl-${PYQTVERSION}.tar.gz
cd PyQt-x11-gpl-${PYQTVERSION}
python configure.py
make
sudo make install
cd ..
\end{bash}

Vous devez bien sûr adapter les instructions en fonction de votre système,
par exemple remplacer \guill{x11} par \guill{mac} pour \guill{macOS}.

\end{document}

